Run for Collection Quick Action (GAD)

•About the Run for Collection Quick Action

•Classic Action Designer Run for Collection Quick Action (CAD)

About the Run for Collection Quick Action

To use this Quick Action, set the global constant EnableActionService to True.

The Run for Collection action allows you to run an action against multiple records in a collection or array. The collection of records can be supplied by an expression or from a webhook, in JSON or XML. This ability means you can create or update business objects based on the data received via a webhook or Web Service Request.

You can also choose whether an action should stop if an error occurs or carry on. The maximum size of a collection is fifty records.

run for collection action block in GAD

Suggestions for Use

Here are a few ways you could use the Run for Collection action:

•Use in conjunction with the Go to Record Quick Action: Specify a JSON or XML collection of records to update, where each entry has a unique identifier for a different record. Use the Run for Collection Quick Action and the Go to Record Quick Action together to iterate over the collection, go to the record for each item in the collection, and perform some action on the record before proceeding to the next.

•Export data from another system and import it into ITSM business objects: If an external system allows the export of data into JSON or XML format, you could map that data to an ITSM business object by defining an action to create a record based from the JSON data. This data could be sent to ITSM via a webhook. Use the Run for Collection Quick Action to create multiple records at once .

Re: data exports, the limit of 50 records per run of an action may not be suitable for bulk imports at this time.

•Enable real-time sharing of data between applications of a business: An external application can send multiple data items in a JSON/XML array to ITSM via webhooks at any time, which ITSM can respond to with the desired action to create or update business objects, send emails, etc.

•Use in combination with another action: You could configure an action, such as the Run REST Web Service Quick Action, that calls an external web service. That web service could return some data in JSON or XML format, which is stored in a variable, and then processed using the Run for Collection Quick Action.

Parameters

To access the parameters select the Action Block to display them in the Settings pane.

Action Block Settings

Block Label: A unique name for the block. This is useful to identify each action when you have more than one of the same action block added or cloned in the design area.

Field	Parameter
Collection to step through	To create an expression to iterate over your chosen collection, click f(x) to open the Simplified Expression Editor. For more information: Using the Simplified Expression Editor. This expression should return the entire collection to iterate over. In most cases, this is a variable such as WebhookBody but it could be any expression. For an example, see Example: Monitoring Server Health Using Run for Collection (GAD)
Action to Run for each Item	Select an action from the drop-down list to run on each record in the collection. The actions listed are those available for the business object you are working with. The action you create (that appears in this drop-down list) should use the CurrentCollectionItem function. Click on Functions > Collections > CurrentCollectionItem to insert the action-specific function CurrentCollectionItem. This functions holds the value of the item in the collection to iterate over, in either text or as an expression pointing to some data, as per the JSONPathValue used in webhook examples. See: Example: Moving Records Using a Webhook The function has context passed into it and knows which unique variable name to use to get the data from. This context is needed because multiple collections from multiple users can be run at the same time, so there needs to be a way to understand which CurrentCollectionItem to get. The CurrentCollectionItem function can ONLY be used with the Run for CollectionQuick Action, so you see an error message if you try to use it with another action.
Stop on Error	If selected, any errors occurring as each record is processed stop the whole iteration and progress is not saved. If not selected, errors are collected but the overall iteration continues and progress is saved up to that point.

Field

Parameter

Collection to step through

To create an expression to iterate over your chosen collection, click f(x) to open the Simplified Expression Editor. For more information: Using the Simplified Expression Editor.

This expression should return the entire collection to iterate over. In most cases, this is a variable such as WebhookBody but it could be any expression. For an example, see Example: Monitoring Server Health Using Run for Collection (GAD)

Action to Run for each Item

Select an action from the drop-down list to run on each record in the collection. The actions listed are those available for the business object you are working with. The action you create (that appears in this drop-down list) should use the CurrentCollectionItem function.

Click on Functions > Collections > CurrentCollectionItem to insert the action-specific function CurrentCollectionItem.

This functions holds the value of the item in the collection to iterate over, in either text or as an expression pointing to some data, as per the JSONPathValue used in webhook examples. See: Example: Moving Records Using a Webhook

The function has context passed into it and knows which unique variable name to use to get the data from. This context is needed because multiple collections from multiple users can be run at the same time, so there needs to be a way to understand which CurrentCollectionItem to get.

The CurrentCollectionItem function can ONLY be used with the Run for CollectionQuick Action, so you see an error message if you try to use it with another action.

Stop on Error

If selected, any errors occurring as each record is processed stop the whole iteration and progress is not saved. If not selected, errors are collected but the overall iteration continues and progress is saved up to that point.

Click Save to commit your changes.

Start Block Settings

These settings are accessed by selecting the Start Block, see Start Block Settings.

Service Log Entries

To see the results of using the Run for Collection Quick Action, open the Service Log. See: Viewing Logs.

You can use the following information to view the outcome of a run, and for diagnostic and debugging purposes:

•The total length of the iteration.

•The number of successes/total.

•The number of failures.

•Failure messages, if any.